Crate tabled

Expand description

An easy to use library for pretty print tables of Rust structs and enums.

The library supports different approaches of table building. You can use Tabled trait if the data type is known. Or you can use Builder to construct the table from scratch.

Usage

If you want to build a table for your custom type. A starting point is to a anotate your type with #[derive(Tabled)].

Then to provide your collection to Table::new and you will be set to render table.

use tabled::{Tabled, Table};

#[derive(Tabled)]
struct Language {
    name: &'static str,
    designed_by: &'static str,
    invented_year: usize,
}

let languages = vec![
    Language{
        name: "C",
        designed_by: "Dennis Ritchie",
        invented_year: 1972
    },
    Language{
        name: "Rust",
        designed_by: "Graydon Hoare",
        invented_year: 2010
    },
    Language{
        name: "Go",
        designed_by: "Rob Pike",
        invented_year: 2009
    },
];

let table = Table::new(languages).to_string();

let expected = "+------+----------------+---------------+\n\
                | name | designed_by    | invented_year |\n\
                +------+----------------+---------------+\n\
                | C    | Dennis Ritchie | 1972          |\n\
                +------+----------------+---------------+\n\
                | Rust | Graydon Hoare  | 2010          |\n\
                +------+----------------+---------------+\n\
                | Go   | Rob Pike       | 2009          |\n\
                +------+----------------+---------------+";

assert_eq!(table, expected);

Not all types can derive Tabled trait though. The example below can’t be compiled.

    #[derive(Tabled)]
    struct SomeType {
        field1: SomeOtherType,
    }

    struct SomeOtherType;

Because tabled must know what we’re up to print as a field, so each (almoust) field must implement std::fmt::Display.

Default implementations

Table can be build from vast majority of Rust’s standard types. This allows you to run the following code.

use tabled::{Tabled, Table};
let table = Table::new(&[1, 2, 3]);

Dynamic table

When you data scheme is not known at compile time. You most likely will not able to relay on Tabled trait.

So one option would be is to use Builder.

use std::iter;

use tabled::{
    builder::Builder,
    settings::{Modify, object::Rows, Alignment, Style}
};

let (x, y) = (3, 10);

let mut builder = Builder::default();

let header = iter::once(String::from("i"))
    .chain((0..y)
    .map(|i| i.to_string()));
builder.set_header(header);

for i in 0..x {
    let row = iter::once(i)
        .chain((0..y).map(|j| i * j))
        .map(|i| i.to_string());
    builder.push_record(row);
}

let table = builder.build()
    .with(Style::rounded())
    .with(Modify::new(Rows::new(1..)).with(Alignment::left()))
    .to_string();

assert_eq!(
    table,
    concat!(
        "╭───┬───┬───┬───┬───┬───┬────┬────┬────┬────┬────╮\n",
        "│ i │ 0 │ 1 │ 2 │ 3 │ 4 │ 5  │ 6  │ 7  │ 8  │ 9  │\n",
        "├───┼───┼───┼───┼───┼───┼────┼────┼────┼────┼────┤\n",
        "│ 0 │ 0 │ 0 │ 0 │ 0 │ 0 │ 0  │ 0  │ 0  │ 0  │ 0  │\n",
        "│ 1 │ 0 │ 1 │ 2 │ 3 │ 4 │ 5  │ 6  │ 7  │ 8  │ 9  │\n",
        "│ 2 │ 0 │ 2 │ 4 │ 6 │ 8 │ 10 │ 12 │ 14 │ 16 │ 18 │\n",
        "╰───┴───┴───┴───┴───┴───┴────┴────┴────┴────┴────╯",
    )
);

Build table using `row!` and `col!` macros.

use tabled::{row, col};

let table = row![
    col!["Hello", "World", "!"],
    col!["Hello"; 3],
    col!["World"; 3],
];

assert_eq!(
    table.to_string(),
    concat!(
        "+-----------+-----------+-----------+\n",
        "| +-------+ | +-------+ | +-------+ |\n",
        "| | Hello | | | Hello | | | World | |\n",
        "| +-------+ | +-------+ | +-------+ |\n",
        "| | World | | | Hello | | | World | |\n",
        "| +-------+ | +-------+ | +-------+ |\n",
        "| | !     | | | Hello | | | World | |\n",
        "| +-------+ | +-------+ | +-------+ |\n",
        "+-----------+-----------+-----------+",
    )
);

use tabled::tables::IterTable;

let iterator = (0..3).map(|row| (0..4).map(move |col| format!("{}-{}", row, col)));

let table = IterTable::new(iterator).to_string();

assert_eq!(
    table,
    "+-----+-----+-----+-----+\n\
     | 0-0 | 0-1 | 0-2 | 0-3 |\n\
     +-----+-----+-----+-----+\n\
     | 1-0 | 1-1 | 1-2 | 1-3 |\n\
     +-----+-----+-----+-----+\n\
     | 2-0 | 2-1 | 2-2 | 2-3 |\n\
     +-----+-----+-----+-----+",
);

Alloc free (`#nostd`)

CompactTable can be configured (’1) to not make any allocations. But the price is that the set of settings which can be applied to it is limited.

It also can be printed directly to fmt::Write to not have any intermidiaries.

’1. It does not make any allocations in case you provide it with width and count_rows.

use tabled::{settings::Style, tables::CompactTable};
use core::fmt::{Write, Result};

struct StubWriter;

impl Write for StubWriter {
    fn write_str(&mut self, _: &str) -> Result {
        Ok(())
    }
}

let data = [
    ["FreeBSD", "1993", "William and Lynne Jolitz", "?"],
    ["OpenBSD", "1995", "Theo de Raadt", ""],
    ["HardenedBSD", "2014", "Oliver Pinter and Shawn Webb", ""],
];

let table = CompactTable::from(data).with(Style::psql());

table.fmt(StubWriter);

More information

You can find more examples of settings and attributes in README.md

Re-exports

pub use crate::tables::Table;

Modules

builderstd
Builder module provides a Builder type which helps building a Table dynamically.
grid
Module is responsible for tables underlyign grid.
macrosmacros
This module contains macro functions for dynamic Table construction.
settings
Module contains various table configuration settings.
tables
Module contains a list of table representatives.

Macros

colmacros
Creates a Table with Display arguments nested within.
rowmacros
Creates a Table with Display arguments nested within.

Traits

Tabledstd
Tabled a trait responsible for providing a header fields and a row fields.

Derive Macros

Tabledderive
A derive to implement a Tabled trait.